<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>cocoOS: docEvents.h File Reference</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>


</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">cocoOS
   &#160;<span id="projectnumber">3.0.0</span>
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.6 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
  <div id="navrow2" class="tabs2">
    <ul class="tablist">
      <li><a href="files.html"><span>File&#160;List</span></a></li>
      <li><a href="globals.html"><span>Globals</span></a></li>
    </ul>
  </div>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('doc_events_8h.html','');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">docEvents.h File Reference</div>  </div>
</div>
<div class="contents">
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>Events are used for task intercommunication and synchronization. For instance, you may want one task to run only when a certain character has been received on the UART. Or you may want one task to pause its execution and wait for two other tasks to execute up to a certain point.</p>
<p>Events are created at system startup in the main function with a call to <a class="el" href="os__appl_a_p_i_8h.html#a04ba027b0848884aa6a2f5a346444be3">event_create()</a>. This function returns a handle (Evt_t) to the created event. This handle is used by the tasks to specify an event when using the event API. When created, the event is in an unsignaled state. When the event is signaled, it is immediately reset to the unsignaled state again. A task can wait for an event by calling <a class="el" href="os__appl_a_p_i_8h.html#a576b2326d068ab852846ee612c7b954c">event_wait(event)</a>. This will immediately put the task in a waiting state until the next time the event is signaled. If a maximum wait time is desired, <a class="el" href="os__appl_a_p_i_8h.html#adf6bffac3935c670ced14cf963fb0427">event_wait_timeout(event, timeout)</a> can be used instead. If the event has not been signalled within the timeout, the task exits the waiting state and continues its execution.</p>
<p>A task can also wait for multiple events with <a class="el" href="os__appl_a_p_i_8h.html#a148bf0f2ab640ccf1cf29229d61defb6">event_wait_multiple()</a>. The first input parameter of this call, specifies if the task shall wait for all events to be signalled or if it shall resume execution when at least one of the events has been signalled. After this parameter follows a list of events which the task shall wait for.</p>
<p>To signal an event, the task call <a class="el" href="os__appl_a_p_i_8h.html#a194e9ed0f676ffc46a782754b58a0475">event_signal()</a>. This will make all tasks waiting for that event, ready to execute. The event itself is automatically reset to an unsignaled state. Note, that the signalling task can be suspended, if any of the waiting tasks have higher priority.</p>
<p>Interrupt service routines should not call <a class="el" href="os__appl_a_p_i_8h.html#a194e9ed0f676ffc46a782754b58a0475">event_signal()</a>, because task switching is not allowed during interrupts. Instead an ISR can call <a class="el" href="os__appl_a_p_i_8h.html#a90cd2126d49864ddb72738c12a01b34e">event_ISR_signal()</a> that will signal the event, but any task switch will be done when both the ISR and the interrupted task has returned.</p>
<p><b> Wait for multiple events Example </b> <br/>
 <br/>
 In the example below, the button_task monitors a button every 20 ms and fires an event when the button is pressed. The com_task waits for a RX event to be signalled from the UART RX ISR. When the event is signalled the task checks the received character, and if it is the updateDisplay character, an event is signalled. The third task, display_task, waits for any of the button or com event to be signalled and updates the display when an event has been signalled. </p>
<div class="fragment"><pre class="fragment">Evt_t ButtonEvent;
Evt_t UartRxEvent;
Evt_t ComEvent;


<span class="keyword">static</span> <span class="keywordtype">void</span> button_task( <span class="keywordtype">void</span> ) {
  <a class="code" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open</a>();  
  
  <span class="keywordflow">for</span> (;;) {
        <span class="keywordflow">if</span> ( BUTTON_PRESSED == checkButton() ) {
                <a class="code" href="os__appl_a_p_i_8h.html#a194e9ed0f676ffc46a782754b58a0475">event_signal</a>( ButtonEvent );
        }
  
        <a class="code" href="os__appl_a_p_i_8h.html#ad8232a672a6d4f3a4532bea410a0b1ef">task_wait</a>( 20 );
  }
  
  <a class="code" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close</a>();
} 



<span class="keyword">static</span> <span class="keywordtype">void</span> com_task( <span class="keywordtype">void</span> ) {
  <a class="code" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open</a>();  
  
  <span class="keywordflow">for</span>(;;) {
        <a class="code" href="os__appl_a_p_i_8h.html#a576b2326d068ab852846ee612c7b954c">event_wait</a>( UartRxEvent );
  
        <span class="keywordflow">if</span> ( UPDATE_DISP_CHAR == uart_getChar() ) {
                <a class="code" href="os__appl_a_p_i_8h.html#a194e9ed0f676ffc46a782754b58a0475">event_signal</a>( ComEvent );
        }
  }
  
  <a class="code" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close</a>();
}


<span class="keyword">static</span> <span class="keywordtype">void</span> display_task( <span class="keywordtype">void</span> ) {
  <a class="code" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open</a>();  
  
  <span class="keywordflow">for</span> (;;) {
        <a class="code" href="os__appl_a_p_i_8h.html#a148bf0f2ab640ccf1cf29229d61defb6">event_wait_multiple</a>( 0, ButtonEvent, ComEvent );
  
        displayUpdate();
  }
  
  <a class="code" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close</a>();
}


ISR (SIG_UART_RECV) {
  rx.data[ rx.head ] = UDR;
  rx.head = ( (rx.head + 1) &amp; BUF_MASK );

  <a class="code" href="os__appl_a_p_i_8h.html#a90cd2126d49864ddb72738c12a01b34e">event_ISR_signal</a>( UartRxEvent );
        
}


<span class="keywordtype">int</span> main( <span class="keywordtype">void</span> ) {
  system_init();
  uart_init();
        
  ButtonEvent = <a class="code" href="os__appl_a_p_i_8h.html#a04ba027b0848884aa6a2f5a346444be3">event_create</a>();
  UartRxEvent = <a class="code" href="os__appl_a_p_i_8h.html#a04ba027b0848884aa6a2f5a346444be3">event_create</a>();
  ComEvent = <a class="code" href="os__appl_a_p_i_8h.html#a04ba027b0848884aa6a2f5a346444be3">event_create</a>();
        
  <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( button_task, 1, NULL, 0,0 );
  <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( com_task, 2, NULL, 0,0 );
  <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( display_task, 3, NULL, 0,0 );
        
  <a class="code" href="os__appl_a_p_i_8h.html#a6cc2e63d83267ff5059bf0a76b302a09">os_init</a>();
  clock_start();
        
  <a class="code" href="os__appl_a_p_i_8h.html#a19c7111cf2121a69331d99dabe3e9df0">os_start</a>();
        
  <span class="keywordflow">return</span> 1;
}
</pre></div><p><b>Event API</b> <br/>
 The event API consists of the following functions and macros:</p>
<ul>
<li><a class="el" href="os__appl_a_p_i_8h.html#a04ba027b0848884aa6a2f5a346444be3">event_create()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#ae28468ad6bb58df9d34ebd5bd3daa548">event_signaling_taskId_get()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a576b2326d068ab852846ee612c7b954c">event_wait()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#adf6bffac3935c670ced14cf963fb0427">event_wait_timeout()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a148bf0f2ab640ccf1cf29229d61defb6">event_wait_multiple()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a194e9ed0f676ffc46a782754b58a0475">event_signal()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a90cd2126d49864ddb72738c12a01b34e">event_ISR_signal()</a> </li>
</ul>
</div></div>
</div>
  <div id="nav-path" class="navpath">
    <ul>
      <li class="navelem"><a class="el" href="doc_events_8h.html">docEvents.h</a>      </li>

    <li class="footer">Generated on Thu Dec 22 2011 21:14:42 for cocoOS by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.6 </li>
   </ul>
 </div>


</body>
</html>
